Monster Media 1994 #2/Monster Media No. 2 (Monster Media)(1994).ISO/utils2/pwrbat22.zip/POWERBAT.DOC

Text File | 1994-05-18 | 125KB | 5,136 lines

                                    PowerBatch
                                  Version 2.2



                         COMPUTING SYSTEMS DESIGN, INC.
                               4437 Ormond Trace
                               Marietta, GA 30066
                               FAX [phone]


                      Copyright (c) 1990-1993 by CSD, Inc.
                         All Rights Reserved Worldwide

               This documentation was produced on April 25, 1994





                               Table Of Contents


                Introduction   . . . . . . . . . . . . . . . . . . . . . . .  1

                Software Support   . . . . . . . . . . . . . . . . . . . . .  3

                Concept Of Operation   . . . . . . . . . . . . . . . . . . .  4

                Installation   . . . . . . . . . . . . . . . . . . . . . . .  6

                Constructing A PowerBatch Source File  . . . . . . . . . . . .  7

                PowerBatch Commands  . . . . . . . . . . . . . . . . . . . . .  9

                Command Summary  . . . . . . . . . . . . . . . . . . . . . . 85

                Compilation Errors   . . . . . . . . . . . . . . . . . . . . 87

                Examples   . . . . . . . . . . . . . . . . . . . . . . . . . 90





                                  Introduction
        PowerBatch is the extension of an original product, PowerBatch,  written
        in late 1989. This product was originally written to provide the user
        an alternative to the standard DOS batch files, an alternative that
        produced standalone executable .EXE programs. The original command set
        was aimed primarily at providing capabilities that solved the classic
        "batch" type application.

        Requests from current users of the product and a desire to provide
        additional capabilities beyond these requests have driven the product
        far beyond original expectations. This product has become not only a
        replacement for solving the classic batch application, but a very high
        level language capable of creating sophisticated applications.

        PowerBatch compiled programs create all the details that are necessary
        to create a professional microcomputer program. When you execute one
        of the PB+ high level commands such as SaveBox, all of the details
        such as memory allocation in the heap area, saving not only the data
        on the screen, but also the color attributes and the cursor location
        are handled just by the invocation of the command. When you execute
        the RestBox command, you do not have to keep track of any of these
        details. PB+ will simply restore the screen area of the last area
        stored and will know where in the heap memory this data is stored,
        move the data, and free up the heap memory that was used.

        This product is intended to provide a novice or beginning programmer
        the capability of producing non-trivial programs with a high success
        rate AND providing the experienced programmer with a tool which makes
        quick work of the task of prototyping new applications.

        Trademarks
        ==========
        PowerBatch is a trademark of Computing Systems Design(CSD), Inc.
        MS-DOS is a trademark of MicroSoft Corporation.
        IBM and PC-DOS are trademarks of IBM Corporation.


        License Agreement
        =================
        a. You are granted a personal, non-transferable and  non-exclusive
        license to use the Program under the terms stated in this Agreement.
        Title and ownership of the Program and documentation remain in CSD,
        Inc.;

        b. the Program may be used by you, your employees, or your agents only


                                    Page 1





        on a single computer;

        c. you and your employees and agents are required to protect the
        confidentiality of the Program. You may not distribute or otherwise
        make the Program or documentation available to any third party;

        d. you may not copy or reproduce the Program or documentation for any
        purpose, except you may copy the Program into machine readable or
        printed form for backup purposes in support of your use of the
        Program. (Any portion of this Program merged into or used in
        conjunction with another program will continue to be the property of
        CSD, Inc. and subject to the terms and condition of this Agreement);

        e. you may not assign or transfer this Program or this license to any
        other person without the express prior consent of CSD, Inc.;

        f. you acknowledge that you are receiving only a limited license to
        use the program and the related documentation. You acknowledge that
        CSD, Inc. retains title to the Program and documentation.  You
        acknowledge that CSD, Inc. has a valuable proprietary interest in the
        Program and documentation; and

        You must reproduce and include the copyright notice on any copy,
        modification or portion merged into another program with the exception
        of compiled executable modules produced from your own source input.
        You may modify the Program for your own use, entirely at your own
        risk, provided that the Program is used as specified in Section (b) of
        this Agreement.

        Output from the PowerBatch compiler generated from original source code
        become the property of the license holder and CSD, Inc. retains no
        rights nor demands any royalty from their use.

        YOU MAY NOT USE, MODIFY, OR TRANSFER THE PROGRAM, OR ANY COPY,
        MODIFICATION OR MERGED PORTION, IN WHOLE OR IN PART, EXCEPT AS
        EXPRESSLY PROVIDED FOR IN THIS LICENSE.

        IF YOU TRANSFER POSSESSION OF ANY COPY, MODIFICATION OR MERGED PORTION
        OF THE PROGRAM TO ANOTHER PARTY, YOUR LICENSE IS AUTOMATICALLY
        TERMINATED.

        TERM
        The license is effective until terminated.  You may terminate it at
        any other time by destroying the Program together with all copies,
        modifications and merged portion in any form.  It will also terminate


                                    Page 2





        upon conditions set forth elsewhere in the Agreement or if you fail to
        comply with any term or condition of the Agreement.  You agree upon
        such termination to destroy the Program together with all copies,
        modifications and merged portions in any form.

        Software Support
        ================
        Support for PowerBatch may be obtained by contacting CSD, Inc. on
        Compuserve using Compuserve Mail (EasyPlex). Address inquiries to
        Compuserve ID 72701,155. If you are not a Compuserve member, you may
        obtain support by writing to:

                            Computing Systems Design, Inc.
                                  4437 Ormond Trace
                               Marietta, Georgia 30066
































                                    Page 3





                              Concept Of Operation

        PowerBatch is a compiler for a very high level language. A high level
        language is one which requires a small number of commands to generate
        code to perform a task. This is at the opposite end of the spectrum
        from a low level language which requires a large number of commands to
        perform a specified task. Low level languages allow the programmer to
        operate at the "bits and bytes" level but generally requires a high
        level of familiarity with both the computer and the language itself.
        Low level languages generally produce code segments that are of
        minimum size and maximum speed. High level languages produce solutions
        that are easier and quicker to develop with some compromise in size
        and speed.

        PowerBatch has attempted to make development of executable modules as
        easy as possible and produce modules that are fast in execution. PB
        Plus+ is a development tool that will allow experienced programmers to
        develop applications in a minimum of time. It is designed to introduce
        non-programmers to the creative world of programming. Error checking
        and all the details that the experienced programmer builds into a
        professional program are included automatically in every PowerBatch
        compiled module.

        In addition to the more than 100 commands in the PowerBatch language,
        any valid executable command (.EXE & .COM) as well as any of the DOS
        intrinsic commands are valid within a PowerBatch source file and will be
        "compiled". These .EXE, .COM and DOS intrinsic commands will be
        executed via a shell and the PowerBatch .EXE program will continue
        execution with the next compiled statement following the shelled
        command. There are two main modules supplied with PowerBatch;
        1)PBPLUS.EXE and 2)SMLMODEL.MDL. PBPLUS reads, parses the source file,
        and compiles the source code extracting routines from SMLMODEL. The
        result is a completely standalone .EXE file that executes without
        SMLMODEL or PowerBatch.

        PowerBatch commands fall into 5 classes of commands;

              1) Commands which provide systems information. These commands
              provide the current color settings, the current date, the
              current time, check for the existence of a valid drive letter,
              and commands which check for the existence of a directory or a
              file.

              2) Commands which control the flow of the program. Execute
              different portions of the program based on existence or non-


                                    Page 4





              existence of directories or files. Compare the contents of one
              variable with the contents of another variable or a constant
              and execute different portions of the batch program based on
              the results of the compare.

              3) Commands which read and write strings of text.  These strings
              of text may be "records" written to a disk as a file or
              elements of an array written to a dynamically expanding array
              in the memory area outside of the compiled program.

              4) Commands which provide string manipulation. Change a string to
              all upper case characters, or all lower case characters.
              Extract a portion of a string such as the first three
              characters or the last four characters. Build a new string from
              two existing strings by concatenation of the two strings.

              5) Commands which deal with screen writing and input from the
              keyboard. These commands are the main power in the PowerBatch
              system. Directly address any position on the screen and move
              the cursor to that position to read or write text.
              Automatically center a message or title on any line. Draw boxes
              around portions of the screen to enhance screen appearance.
              Read a single key from the keyboard, read the response to a
              query that only accepts a yes or no response, read a string of
              characters from the keyboard with a specified maximum length,
              and read keys from the keyboard automatically changing the
              characters to upper case.




















                                    Page 5





                                     Installation

        Installation is accomplished by executing the PBInstal program. It
        seemed only fitting that this install program be a compiled PowerBatch
        program.  The two main modules PB PLUS.EXE and SMLMODEL.MDL must be
        located in the DOS path to allow you to compile PowerBatch programs from
        any directory on your system. PowerBatch may be run on a system as small
        as a single floppy drive system with 128K. There will be some limit to
        the number of source statements that may be compiled on a system this
        small as memory is dynamically allocated as compilation progresses. A
        source file of several hundred statements can be compiled on a small
        machine. The PBInstal program is strictly a file copy program. It will
        ask you where you wish to place the PowerBatch files and copy them to
        the specified directory. You may copy your own files to various
        directories if you desire. You may even copy PBPLUS.EXE and
        SMLMODEL.MDL to a directory not on your path if you desire. If you do
        so, you may compile only from the directory containing these two
        files.

        PowerBatch may be installed from either drive A or B.

        Place your PowerBatch installation disk in either drive A or drive B.
        Change to the drive which contains the install disk by typing
           A: <Enter>
        or
           B: <Enter>

        Run the installation program by entering

           PBINSTAL <Enter>

        Follow the onscreen instructions to copy both the compiler and the
        example files to your disk. Remember that you must copy both
        PBPLUS.EXE  and  SMLMODEL.MDL to a directory defined to be in the DOS
        search path in order to compile programs from any directory. If you do
        not place these programs in a directory on the search path, you will
        be able to compile from only the directory where they reside.










                                    Page 6





                         Constructing A PowerBatch Source File

        Use your favorite text editor to create a printable ASCII file
        containing PowerBatch source commands and DOS executable commands. A
        printable ASCII file is one that may be typed to the screen (i.e. type
        myfile.pwr <enter>) and the results printed on the screen contain only
        the file contents. Most files created with a word processor are not
        printable ASCII files unless you specify an ASCII file output option.

        Compile your source statements to create a .EXE executable module.
        This is done using the PowerBatch compiler. The syntax is:

           PBPlus MyFile [OutFile] [+M] [+D2] [+O]

        PowerBatch assumes the extension of the input file to be .PWR (i.e.
        MYFILE.PWR) and will create an output file of MYFILE.EXE if no OutFile
        parameter is specified. The input source file may be any DOS name of
        your choice (including the extension). You may also specify an output
        file name of your choice but the extension will always be .EXE. If you
        do not enter the input file name on the command line, the program will
        prompt you for the name. You must at this time enter the complete name
        including the extension.

        If you wish to generate a list of all literals, variables, and labels
        used in your PowerBatch program, add +M to the end of the command line.
        This variable map will be written to the [FileName].MAP file.

        If you will be running the output from the compilation on any computer
        that is operating under a version of DOS that is earlier than DOS
        version 3.0, you must enter the compiler directive +D2. This directive
        will cause the compilation to be much slower but the resulting .EXE
        file will execute on computers running on DOS 3.0 and up at the SAME
        SPEED as compilations made without the +D2 directive. If in doubt, use
        +D2. A minute of compile time will eliminate future problems. If you
        compile a program that has been compiled before and has generated an
        .EXE file, you will be asked if you wish to replace this EXE file. To
        compile in batch mode or to bypass this message use the overwrite parm
        +O.

        If the compiler finds no compilation errors, the compiled version of
        your source file will be generated. For an explanation of compilation
        errors, see the section entitled "Compilation Errors". Compilation
        errors appear on your screen as they are encountered and they are
        written to a file named [FileName].MAP (i.e. if your input file name
        is MYFILE.PWR, the error and map file will be MYFILE.MAP). The entire


                                    Page 7





        source code is scanned each time you compile a PowerBatch program (i.e.
        the compiler does not stop when an error is found, but attempts to
        identify all errors on each pass). This means that some errors will be
        the result of previous errors found in the source.

        If there are no compilation errors, the [FileName].MAP file will not
        be created.








































                                    Page 8





                                  PowerBatch Commands

        Commands, Variable Names, and Labels are not case sensitive.
        Everything on the command source line is converted to upper case
        except a literal which is enclosed within quotes. Either single
        quotes(') or double quotes(") may be used to denote a literal.
        Literals which are numeric such as color values, variable lengths,
        etc. should not be enclosed in quotes. The compiler does evaluate each
        literal (both alpha and numeric) in the same manner. The evaluation
        process is 1) remove leading and trailing quotes if any, 2) attempt to
        convert literal to numeric, 3) if numeric conversion is successful,
        consider it a number, 4) if numeric conversion is unsuccessful,
        consider it alpha numeric. This means that internally an operand of 3
        and "3" will both be numeric.

        A semicolon which is not enclosed within quotes or a part of a command
        is used to denote a comment. Semicolons which are part of a command
        must not be preceded by a space. A comment begins with a semicolon
        which follows a space not within quotes. Comments may appear anywhere
        on the command line, but everything after a semicolon on a command
        line is ignored. A comment may begin in column 1 by placing the
        semicolon in column 1. The following are NOT comments:

           path=d:\;c:\util;c:\wp
           path   "d:\;c:\util;c:\wp"
           WriteLine   "Punctuation may be used within quotes;"

        These ARE comments:

           Variable ColorSave,3 ;save the original color
           SetVar   Msg, ErrMsg ;set Msg to "Invalid input"

        The starting location on the command line of the command and the
        operands is not important and tabs and spaces may be freely used for
        readability.

        Variable names and command labels may be any length in the source but
        are significant only through the first eight positions. This means
        that any variable name or label that is equal in the first 8 positions
        will be considered the same.

        Variables, Literals, and Labels

        Variables
        A variable is a location in memory that you allocate and give a name


                                    Page 9





        and a maximum length. Anytime you refer to the "name" of the variable,
        you are referencing the memory locations set aside for this variable.
        Variable names give you an easy way to manipulate data internally
        within the computer. The following are examples of variables:

           Variable    CharIn,1

        This variable gives the name "CharIn" to one memory position. It might
        be used to hold one character responses from the keyboard by the user.


           Variable    PBDir,79

        This variable appears in the PBInstal program and holds the name of
        the directory where the PowerBatch compiler will be placed. It is
        composed of the drive letter and directory entered by the user in
        response to two questions during the installation process.

           Variable    CompName,35,"The ABC Company"

        This variable reserves 35 positions in memory and gives these
        locations the name CompName. The PowerBatch compiler also places the
        initial value "The ABC Company" in the first 15 positions of the
        variable. The value of this variable may be changed by later
        processing in the program. When this variable is referenced in the
        program it will contain only 15 characters (The ABC Company) with no
        leading or trailing spaces, assuming the program has not assigned a
        new value.

           Variable    MsgClear,20,"                    "

        This variable contains 20 spaces and is named MsgClear. It will be
        used to "clear" or overwrite with spaces an error message in your
        program. Once you have displayed a message to the user, it should be
        cleared as you continue with the program. This is done by overwriting
        with spaces. Having a variable with the correct number of spaces makes
        this task easier.



        Literals
        Literals are very much like variables which have a value but no name.
        Literals are used in PowerBatch commands when you wish to pass an actual
        value to the command instead of a variable. Note in the following
        examples that literals containing numbers only are not enclosed in


                                    Page 10





        quotes and literals containing any non-numeric characters are enclosed
        in quotes. If you specify a number as a literal, either convention is
        acceptable (3 or "3"). If you specify alphabetic characters, the
        quotes are required. For readability, and ease of entry, numeric
        literals usually do not contain quotes. Examine the following examples
        of literals:

           Center      "Installation Program",1

        This command will center the literal "Installation Program" on line 1
        of the screen. The text "Installation Program" must appear somewhere
        in the program and it appears as a literal. It will occupy memory
        positions and will have a value but you may not reference this value
        by name. By instructing the compiler to write this literal, the
        compiler automatically creates the memory locations and initial value
        but gives it no name. The 1 is also a literal in this command. Each
        time you use a literal in a PowerBatch program, the previously assigned
        literals are checked for duplication and if the literal has been
        previously assigned, the prior assignment will be used (i.e. literal
        values will appear only one time regardless of the number of times
        used).

           WriteAt     12,3,Msg1

        There are two literals in this command. The numbers 12 and 3 are both
        created as literals. In this command they specify the column and row
        location where the string Msg1 will be written. Again, the compiler
        creates the memory locations and values for these literals, but no
        names. If you were to write another command such as the Beep command
        which specifies that the system speaker will beep at a certain
        frequency for 3 times, the compiler will find the previously defined
        literal "3" and use this value instead of creating another literal.

           Beep        ErrTone,8,3

        This is the Beep command referenced in the previous example. The beep
        command will cause the speaker to sound at a frequency of ErrTone for
        .8 second and repeat 3 times. The "3" literal will use the same memory
        location reference as the WriteAt command used in the previous command
        (i.e. another literal will not be created).

        Labels





                                    Page 11





        Labels are names of a particular place in your PowerBatch program that
        you will go to without executing the previous command. You go directly
        to this location in the program from another location in the program
        based on a decision you have made in the code flow. Examples will help
        explain:

           ReadYN      "Do you wish to continue [Y/N] ",InChar
           Compare     InChar,"Y",,,GetDrive
           Halt        999      ;end the program if "N"

           Label       GetDrive

        This group of commands writes the message on the screen and asks the
        user to input either Y or N (the command will only accept these two
        characters). A comparison is then made to a literal "Y" and the
        compare command will jump to the location in the program named
        GetDrive if a "Y" was entered or will execute the next command if "N"
        was entered.
           GoTo        NextCmd
           .
           .
           .
           Label       NextCmd

        In this most straightforward use of the label, the user simply uses
        the GoTo command and jumps unconditionally to another point in the
        program.

        External Commands
        External commands are entered just as PowerBatch commands are entered.
        If you enter an external command and this command uses command line
        parameters, these parameters may be passed as either variables or
        literals. Remember that if the parameter is not numeric, it must be
        enclosed in quotes or it will be treated as a variable. Any PowerBatch
        statement which is an external command may contain a maximum of 7
        command line variables. That is not to say that you may not pass more
        than 7 command line parameters to an external program but that these
        command line variables may not be contained in more that 7 PowerBatch
        variables.

        For example:
           Variable Parm1,5,"one"
           Variable Parm2,5,"two"
           Variable Parm3,5,"three"
           Variable Parm4,5,"four"


                                    Page 12





                           Variable Parm5,5,"five"
           Variable Parm6,5,"six"
           Variable Parm7,5,"seven"
           Variable Parm8,5,"eight"
           Variable BigParm,80

           ExtPgm   (Name of an external program)

        A valid method for passing these parms in one PowerBatch parameter.

           Extpgm   "one two three four five six seven eight"

        Accomplishing the same thing with variables using 6 PowerBatch parms.

           Concat   BigParm,Parm1," "
           Concat   BigParm,Parm2
           Concat   BigParm," "
           Concat   BigParm,Parm3
           ExtPgm   BigParm,Parm4,Parm5,Parm6,Parm7,Parm8

        Examples of external programs as PowerBatch commands:

           Variable    InChar,1
           ReadYN      "Do you wish a directory ",InChar
           Compare     InChar,"Y",NextSec,NextSec
           DIR         "/W"
           SETUP    "> null"    ;printer redirection

           Variable    PgmName,12
           Write    "Enter program name to compile "
           ReadStr     PgmName
           TPC         PgmName, "/ddebug"

        This third example of external commands show the use of two predefined
        variables, ERRORLEVEL and DOSERROR. After the execution of "TestPgm",
        we examine DOSError to find if the program executed OK (Possibly there
        was not enough memory or the program could not be found on the DOS
        path). After determining that the program executed OK, we examine the
        exit code set by "TestPgm" to determine the flow of the remainder of
        our program. This exit code will be found in the variable ERRORLEVEL.

           Variable    MsgLine,80
           .
           .
           TestPgm     "Parm1 Parm2"


                                    Page 13





                           Compare     DOSError,0,,,RanOK
           WriteLine      "TestPgm did not execute properly"
           Halt        DOSError
           Label    RanOK
           Compare     ErrorLevel,1,Chk2,,Option1
           Concat      MsgLine,"Unexpected code : ",ErrorLevel
           Halt
           Label       Option1

        Note: PowerBatch programs may be executed by other PowerBatch programs as
        external commands. An option of the PowerBatch Halt command is to set
        the DOS errorlevel. You could then "pass parameters" from one PowerBatch
        program to another via the ERRORLEVEL variable.

        Command Line Parameters
        Command line parameters may be passed to a compiled PowerBatch program.
        These command line parameters must be defined at compile time and have
        special variable names. Up to 16 parameters may be passed to a PB
        Plus+ program. These parameters are named CLP%1 - CLP%16.
        If you wish to pass parameters on the command line to your PowerBatch
        program, define the command line parameter variables (CLP%1 - CLP%16)
        in your PowerBatch source prior to compilation and when you run the
        compiled program, any parameters entered on the command line will be
        in the defined variable. Example:

           Source for SMARTCPY.PWR

           Variable    CLP%1,79    ;source file
           Variable    CLP%2,79    ;target file
           Variable    InChar,1
           ReadYN      "Ready to copy the files [Y/N] ",InChar
           Compare     InChar,"Y",NoCopy,NoCopy
           COPY        CLP%1, CLP%2

        SMARTCPY FILE1 FILE2 will execute the DOS copy command and copy FILE1
        to FILE2 if the user responds Y to the question.

        Changing Environment Variables

        Your computer memory contains a special area of memory called the
        "Environment Area". This special area of memory contains the values
        assigned to variables that are available to the DOS operating system
        or to any application program running in your computer. These values
        remain unchanged until DOS or an application program changes them. DOS
        maintains special values in this area which the operating system uses.


                                    Page 14





        Your current path and current prompt configuration are two of these
        values. These values are normally set with the DOS PROMPT or PATH
        command. If an application program like a compiled PowerBatch program
        executes a DOS command, it is done via a "shell" or another copy of
        your command processor (normally COMMAND.COM) which is started to
        handle the execution of these DOS commands. When a shell is started,
        DOS creates a copy of the environment area for this new shell and
        makes the environment values available to the shell. Unfortunately,
        when the shell is terminated (when the DOS command is complete) this
        copy of the environment is erased from memory. If you execute a
        PROMPT, PATH or SET [Variable] command, the copy of the environment
        created for the shell to run the PROMPT, PATH, or SET command is
        updated and immediately erased when the PowerBatch program is finished.
        PowerBatch however, provides you a means to update both the permanent
        copy and the current copy of the environment area with the commands
        SETPATH, SETENV, and PROMPT.

        Unfortunately, problems dealing with the environment area do not end
        here. When DOS runs a program (like a PowerBatch compiled program), a
        copy of the permanent environment is made and is the "active"
        environment area in use during the running of the program. If you only
        read the values of existing environment variables, there is no
        problem. If you attempt to add new environment values, the amount of
        free environment space is very limited. IT IS NOT THE AMOUNT OF SPACE
        ALLOCATED BY YOU IN YOUR CONFIG.SYS FILE (or the default) MINUS THE
        AMOUNT OF USED SPACE! The amount of "free" space appears to be only
        the amount left after rounding up the amount of used space to the
        nearest paragraph of memory (16 bytes).
        The problem of allocating environment free space can be circumvented
        by updating the permanent environment area with dummy values prior to
        the execution of your PowerBatch file. This could be done with a small
        PowerBatch program such as ENV-INIT.PWR as follows:

           SetEnv   Env1,'dummy value dummy value'
           SetEnv   Env2,'dummy value dummy value'
           .
           .
           .
        When ENV-INIT terminates, the environment variables Env1 and Env2 will
        have the dummy values and will now be a part of any environment area
        copy passed to a running program. You could of course use the DOS SET
        command from the DOS command line or initialize the environment
        variables with dummy values in your AUTOEXEC.BAT file.

        Command Notation


                                    Page 15





        In the description of the commands which follow, that which appears
        within brackets [ ] is optional and all other operands are required.
        Any time a screen color may be specified in a command such as

           CLEARLINE LineNum,ForegrClr,BackgrClr

        the single attribute which is used in many color conventions may be
        substituted for the pair of color attributes. For example, foreground
        color 4 (red), background color 1 (blue), is identical to color
        attribute 20 and the CLEARLINE command may be specified EITHER as

           CLEARLINE 14,4,1
        or
           CLEARLINE 14,20

        to clear line 14 on the screen to red foreground on blue background.
        For this reason anytime that the operand pair of foreground color,
        background color is required, the single color attribute may be
        substituted for the pair. The compiler will not detect missing
        background color attributes but will assume that the foreground is the
        composite value.

        How do I calculate this color attribute? The composite color attribute
        is the DOS shorthand method of keeping both the foreground and
        background colors in one byte of memory. It may be calculated by
        multiplying the background color by 16 and adding the foreground
        color. See Appendix B for a complete list of composite color
        attributes.

        Color Attribute = (Backgrnd X 16) + Foregrnd
        RedOnBlue = (1 X 16) + 4 = 20
        WhiteOnBlack = (0 X 16) + 7 = 7
        YellowOnRed = (4 X 16) + 14 = 78
        DOS uses the ASCII values 0 through 127 for all the colors available.
        To make any color blink, add 128 to the color value.

        YellowOnRed,Blinking = 78 + 128 = 206.

        Command Syntax

        Several examples are available on the distribution disk. All source
        code examples have a file extension of .PWR. These examples may be
        edited with your favorite text editor and printed by "copying" the
        file to the printer such as COPY PBINSTAL.PWR LPT1.



                                    Page 16





                       ?COLOR Foreground, Background, Composite

        Retrieve the current color attributes from the system and place the
        current foreground color in ForeGround, the current background color
        in BackGround, and the composite attribute in Composite. The
        relationship is Composite = (BackGround * 16) + ForeGround. See
        Appendix B for complete list of composite color attributes.

              Variable ForeColor,3
              Variable BackColor,3
              Variable ColorAttr,3
              ?Color   ForeColor,BackColor,ColorAttr

        Retrieve the current foreground, background and composite color values
        and place in the variables ForeColor, BackColor, and ColorAttr
        respectively. To create professional programs it is a good idea to
        retrieve the current color setting as the first command in the program
        and reset these values and clear the screen at the end of your
        program. This restores the users computer to the same color state that
        you found when your PowerBatch program was executed.



























                                         Page 17





                          ?CURRDIR CurrDrive, CurrDirectory

        Retrieve the current drive and directory from the system and place the
        current drive in CurrDrive and the current directory in CurrDirectory.
        The contents of CurrDrive prior to execution of this command control
        which drive is searched for the currently logged directory. If
        ?CurrDir finds a valid drive letter in the first position of
        CurrDrive, then the contents of CurrDirectory will be the currently
        logged directory of that drive. If the first position of CurrDrive
        does not contain a valid drive letter, then CurrDirectory will contain
        the currently logged directory of the current drive. In either case
        CurrDrive will contain the drive and CurrDirectory will contain the
        directory.

           Variable    CurrDrive,2
           Variable    CurrDir,79
           SetVar      CurrDrive,"A"
           ?CurrDir    CurrDrive,CurrDir
           SetVar      CurrDrive,""
           ?CurrDir    CurrDrive,CurrDir

        In the first usage of ?CurrDir, assuming that the currently logged
        directory on the A drive is the root directory, CurrDrive will contain
        "A" and CurrDir will contain "\" after the execution of ?CurrDir. In
        the second usage, assuming that the currently logged drive is D: and
        the currently logged directory on the D: drive is "\UTIL\EXEC",
        CurrDrive will contain "D" and CurrDir will contain "\UTIL\EXEC" after
        the execution of ?CurrDir.



















                                    Page 18





                          ?DATE DayOfWeek, Month, Day, Year

        Retrieve the current date from the system and place the day of the
        week in DayOfWeek, the month in Month, the day in Day, and the 4 digit
        year in Year. DayOfWeek should be defined as 9 long, Month and Day as
        2 long, and Year as 4 long.

           Variable DOW,9
           Variable Mo,2
           Variable Da,2
           Variable Yr,4
           ?Date DOW,Mo,Da,Yr

        Retrieve the current date and place the component parts in their
        respective variables. Place the day of the week in DOW (i.e.
        Saturday), the month number in Mo (i.e. 06), the day of the month in
        Da (i.e. 29), and the year in Yr (i.e. 1993).






























                                    Page 19





                      ?DIREXIST DirName, FoundLbl [,NotFoundLbl]

        Check the system for the existence of the directory whose name appears
        in DirName. If the directory exists go directly to the label FoundLbl,
        if the directory does not exist, go directly to the label NotFoundLbl.
        DirName may either be a variable or a literal. If NotFoundLbl is not
        specified, execution will continue with the next instruction
        immediately following the ?DirExist command.

           ?DirExist   InpStr,DirOk,BadDir
           ?DirExist   "C:\",DirOK,BadDir
           ?DirExist   InpStr,,BadDir  (next command if exists)
           ?DirExist   InpStr,DirOk    (next command if not exist)

        In the first example if the contents of the variable InpStr exists
        then goto label DirOK, if it does not exist go to the label BadDir. In
        the second example we check for the existence of a directory contained
        in the literal whose value is "C:\". In the third example, if the
        contents of InpStr exist we "fall through" to the next instruction, if
        the directory does not exist we jump to the label BadDir. In the
        fourth example, if the directory name in InpStr exists, we jump to the
        label DirOK, if it does not exist we fall through to the next command.

























                                    Page 20





                                               ?DISKINFO DriveLetter, VolID, DriveType

        The volume ID is retrieved from the DriveLetter drive and the type of
        drive is determined and placed in DriveType. Volume ID may be a string
        of up to 12 characters. All disk media is not required to contain a
        Volume ID and in this case VolID will contain "No Label". The
        DriveType will be one of the following values:
           "360 Floppy"      "720 Floppy"      "1.2 Floppy"
           "1.4 Floppy"      "Other Floppy" "Bernoulli"
           "HardDisk"     "RamDisk"      "SubDrive"
           "Unknown"      "Invalid"

           Variable Drive,1,'D'
           Variable VolumeID,12
           Variable DriveType,12

           ?DiskInfo   Drive,VolumeID,DriveType
           Compare  DriveType,'RamDisk',,,RamOK
           Write Drive
           WriteLine   ' is not a RAM drive!'
           Halt

           Label RamOK
























                                    Page 21





                    ?DISKSPACE DriveLetter, TotalSpace, FreeSpace

        Query the disk Drive specified by the first character of DriveLetter
        and place the total disk capacity in bytes in TotalSpace and the
        unused bytes in FreeSpace. Since the command looks at only the first
        character of DriveLetter, this parameter may contains strings such as
        "C:\UTIL". DriveLetter may be either a Variable or a Literal.

           Variable    DirName,79
           Write    'Enter your full pathname'
           ReadStr     DirName  (user enters "c:\util")
           ?DiskSpace  DirName,TotSpace,FreeSpace

        This will place the total capacity of drive C: in the variable
        TotSpace and the amount of this space that is unused in the variable
        FreeSpace.

           ?DiskSpace  "A",TotSpace,FreeSpace

        This retrieves the total capacity and free space for drive A:  using a
        literal of "A".


























                                    Page 22





                 ?DRIVEEXIST DriveLetter, ValidLabel [,InvalidLabel]

        Check the system for DriveLetter as a valid drive. If the drive is
        valid, jump to Label1, if the drive is not valid, jump to Label2. If
        InvalidLabel is not specified, execution will continue with the next
        command immediately following the ?DriveExist command. DriveLetter may
        be either a variable or a literal.

           ?DriveExist DrvNum,GoodDrv,BadDrv
           ?DriveExist "A",GoodDrv,BadDrv
           ?DriveExist DrvNum,,BadDrv (falls thru if drive ok)
           ?DriveExist DrvNum,GoodDrv (falls thru if drive bad)



































                                    Page 23





                       ?ENVSTR EnvironName, EnvironNameContents

        Retrieve the contents of any environment variable from the system
        environment area. The name of the environment variable is placed in
        EnvironName or entered as a literal and the contents of the
        environment variable will be placed in EnvironNameContents. Ensure
        that EnvironNameContents has been defined long enough to contain the
        contents of the environment variable. If EnvironNameContents is not
        long enough, the environment variable will be truncated. To display
        the currently defined environment variables, use the DOS "SET" command
        at a DOS prompt. (i.e. C:>SET <enter>) You should receive at least two
        environment variables (assuming you have set a path) with the format
        NAME=VALUE. The location of your command processor is in an
        environment variable named COMSPEC and should look something like
        this: COMSPEC=C:\COMMAND.COM.

           Variable    EnvValue,255
           Variable    EnvName,4,"path"
           ?EnvStr     "prompt", EnvValue
           ?EnvStr     EnvName, EnvValue



























                                    Page 24





                   ?FILEEXIST FileName, FoundLabel [,NotFoundLabel]

        Check the system for the specified file name. If the file exists, jump
        to the label FoundLabel, if the file does not exist, jump to the label
        NotFoundLabel. If NotFoundLabel is not entered, execution will
        continue with the next command immediately following the ?FileExist
        command. If only a file name is entered (i.e. CONFIG.SYS), then only
        the current directory will be searched. If a fully qualified filename
        is entered (i.e. C:\CONFIG.SYS), then only the specified directory
        will be searched. FileName may be either a variable or a literal. See
        ?FileExpand.

           ?FileExist  FileName, Label1, Label2
           ?FileExist  "C:\AUTOEXEC.BAT",StartOK,NoStart
           ?FileExist  FileName,,NotFound
           ?FileExist  FileName,Found

        The two commands ?FileExist and ?FileExpand are identical with the
        exception that ?FileExist gives you the capability to limit your
        search to the current directory while ?FileExpand will attempt to find
        the file anywhere on the disk and tell you exactly where the file was
        found.

























                                    Page 25





                  ?FILEEXPAND FileName, FoundLabel [,NotFoundLabel]

        Check the system for the specified file name. If the file exists, jump
        to the label FoundLabel, if the file does not exist, jump to the label
        NotFoundLabel. If NotFoundLabel is not entered, execution will
        continue with the next command immediately following the ?FileExist
        command. If FileName contains a drive and/or path in addition to the
        filename (i.e. C:\CONFIG.SYS or \CONFIG.SYS), the specified drive and
        directory is searched. If only a filename is placed in FileName, then
        the search contains the following: 1) the current directory, 2) the
        directory from which the compiled PowerBatch program was run, 3) all
        directories on the search path. (I try to find it in any directory on
        the disk which I know exists). If the file was found, the full path
        name\filename is placed in FileName. For this reason FileName must be
        a variable. Ensure that FileName is long enough to handle this full
        pathname!

           SetVar      FileName,'MYFILE.LTR'
           ?FileExist  FileName, Label1, Label2

        Assuming that MYFILE.DAT was located in "\WP60\LETTERS", the contents
        of FileName will be "C:\WP60\LETTERS\MYFILE.LTR".

           ?FileExist  "C:\AUTOEXEC.BAT",StartOK,NoStart

        ERROR! FileName cannot be a literal.

        The two commands ?FileExist and ?FileExpand are identical with the
        exception that ?FileExist gives you the capability to limit your
        search to the current directory while ?FileExpand will attempt to find
        the file anywhere on the disk and tell you exactly where the file was
        found.















                                    Page 26





                             ?FILESIZE FileSize, FileName

        The size in bytes of FileName is placed in FileSize. FileName may be
        either a variable or a literal. FileSize must be a variable.

           Variable FileSize,11
           Variable FileName,'AUTOEXEC.BAT'

           CD    'C:\'       ;change drive and dir
           ?FileSize   FileSize, FileName   ;find the filesize
           ?FileSize   FileSize, 'AUTOEXEC.BAT' ;same results




































                                    Page 27





                    ?INPATH DirName, FoundLabel, [,NotFoundLabel]

        Compare the contents of DirName to the system search path. If DirName
        is contained within the path, jump to the label FoundLabel, if DirName
        is not contained within the path, jump to the label NotFoundLabel. If
        NotFoundLabel is not specified, execution will continue with the
        command immediately following the ?InPath command. Use this command to
        determine if a directory is located in the DOS search path.

           DOS search path contains "C:\UTIL;C:\WORDPROC;D:\"
           Variable    InString,79
           Write    "Enter your directory name "
           ReadStr     InString (user enters "c:\wordproc")
           Upper    InString (change to "C:\WORDPROC")
           ?InPath     InString,PathOK,BadPath

           ?InPath     "C:\UTIL",,BadPath   (compare literal)






























                                    Page 28





                                  ?TIME CurrentTime

        Retrieve the current time from the system and place in CurrentTime.
        The format of the time is hh:mm:ss xm. CurrentTime should be defined
        as 11 long.

           Variable CurrTime,11
           ?Time CurrTime (now contains 11:24:14 am)







































                                    Page 29





                        ADD Sum, Number, [RtnCode], [Decimals]

        Add the contents of Number to Sum and place the result in Sum. RtnCode
        will contain zero (0) if the add command completed without error.
        Decimals contains the number of decimal places for the result. If
        Decimals is not specified, zero decimal places will be assumed and
        integer arithmatic will be performed. Your Result will be rounded to
        the specified number of decimal places.  Accurate to 18 significant
        digits.

           Variable    YLoc,2
           SetVar      YLoc,6
           Label    LoopCtr
           ClearLine      YLoc,Blue
           Add         YLoc,1
           Compare     YLoc,11,LoopCtr

        This small code segment will clear lines 6 through 10 on your screen
        by incrementing the line number variable used by the ClearLine
        command.

        Using decimals with PowerBatch math...

           Variable    AcctBal,12,'127,854.94'
           Variable    RtnCode,1
           Add         AcctBal,'122.125',RtnCode,4
           Compare     RtnCode,0,ErrRtn
           Write    AcctBal     (contains 127977.065)
           Multiply    AcctBal,'.000325',RtnCode,6
           Compare     RtnCode,0,ErrRtn
           Write    AcctBal     (contains 41.592546)
















                                    Page 30





                          BEEP Frequency, Duration [,Repeat]

        Sound the system speaker with a tone of Frequency, for a length of
        Duration tenths of a second, and repeat Repeat times.

           Beep  800,5,3
           Beep  ErrFreq,BeepLen,ErrTimes

        The first example sounds the system speaker at a frequency of 800 hz
        for half a second (.5) and repeats twice for a total of 3 times. The
        second example will sound the system speaker at a frequency equal to
        the contents of the variable ErrFreq for BeepLen tenths of a second(s)
        for a total of ErrTimes.


































                                    Page 31





                                        BLINK

        Cause all text that is written to the screen to blink using the
        current color attributes last defined in the processing of the your
        program. This command in "undone" by using NORMAL.

           Variable MsgClear,25."                         "
           Blink
           WriteAt  15,4,"Not a valid entry"
           Normal
           Wait     35
           WriteAt  15,4,MsgClear

        Write the message "Not a valid entry" at column 15 on row 4 using the
        current color definition. Reset the text color to the value it
        contained before specifying blinking text. Wait 3.5 seconds and clear
        the message.






























                                    Page 32





                                         BOOT

        This command will cause the computer to perform a "warm" boot. This
        emulates the pressing of the Alt-Ctrl-Del key combination.

           ReadYN   'Press Y to REBOOT your machine (Y/N) ',YNInput
           Compare  YNInput,'Y',NoBoot,NoBoot
           Boot
           Label NoBoot






































                                    Page 33





                       BOXx UX, UY, LX, LY, ForeClr [,BackClr]

        Where Boxx is Box0 thru Box3. Draw a box (frame) on the screen whose
        upper left coordinates (X,Y) are UX,UY, and whose lower right
        coordinates (X,Y) are LX,LY. Draw the box using a line in foreground
        color ForeClr on background color BackClr. The border line for the box
        is:
           Box0 - No border
           Box1 - Single line
           Box2 - Double line
           Box3 - Heavy solid line.
        The interior of the box is cleared to the background color whether
        specified explicitly by the background color parameter or as a part of
        the composite color parameter. The cursor is positioned at UX+1, UY+1.

           Variable ULX,2,5     ;upper left col value
           Variable ULY,2,3     ;upper left row value
           Variable LRX,2,75    ;lower right col value
           Variable LRY,2,20    ;lower right row value
           Variable BoxFore,2,4 ;foreground color red
           Variable BoxBack,2,0 ;background color black
           Box1     ULX, ULY, LRX, LRY, BoxFore, BoxBack
           Box1     5,3,75,20,7,0
           Box1     5,3,75,20,112

        The first example draws a box whose upper left coordinates are the
        contents of the variables ULX and ULY and whose lower left coordinates
        are the contents of the variables LRX and LRY. The box border will be
        the contents of BoxFore (red) on a background of BoxBack (black).  The
        second example draws a box whose upper left coordinates are 5,3 and
        whose lower right coordinates are 75,20. The box border is drawn in
        white on black. The third example draws a box with the same
        coordinates and uses the composite color attribute of 112 (white on
        black). See ClearBox command.













                                    Page 34





                 BOX4 UX, UY, LX, LY, ForeClr [,BackClr] [,ShadowClr]

        Draw a box (frame) on the screen whose upper left coordinates (X,Y)
        are UX,UY, and whose lower right coordinates (X,Y) are LX,LY. Draw the
        box using a line in foreground color ForeClr on background color
        BackClr. The border line for the box is single line with a transparent
        shadow. The shadow color is ShadowClr.

        The interior of the box is cleared to the background color whether
        specified explicitly by the background color parameter or as a part of
        the composite color parameter. The cursor is positioned at UX+1, UY+1.

           Variable ULX,2,5     ;upper left col value
           Variable ULY,2,3     ;upper left row value
           Variable LRX,2,75    ;lower right col value
           Variable LRY,2,20    ;lower right row value
           Variable BoxFore,2,4 ;foreground color red
           Variable BoxBack,2,0 ;background color black
           Variable Shadow,2,8  ;shadow color
           Box1     ULX,ULY,LRX,LRY,BoxFore,BoxBack,Shadow


        This example draws a box whose upper left coordinates are the contents
        of the variables ULX and ULY and whose lower left coordinates are the
        contents of the variables LRX and LRY. The box border will be the
        contents of BoxFore (red) on a background of BoxBack (black). The
        shadow color is the contents of the variable Shadow. See ClearBox
        command.



















                                    Page 35





                                       BREAKON


        Provides a capability to exit from a PowerBatch program by pressing the
        combination of keys (Ctrl - Break) or (Ctrl - C). The default value
        set at the beginning of any PowerBatch program is BreakON. To keep a
        user from exiting a running PowerBatch program, execute the BreakOFF
        command. If sections of the program are to be protected and other
        sections not protected, surround the sections with pairs of
        BreakON...BreakOFF commands. See BreakOff command.





































                                    Page 36





                                       BREAKOFF

        Disables the ability to stop a PowerBatch program by pressing the (Ctrl
        - Break) or (Ctrl - C) key combinations. The default value set at the
        beginning of any PowerBatch program is BreakON. See BreakOn command.










































                                    Page 37





                             CENTER TextToCenter, LineNum

        TextToCenter is centered on LineNum. If LineNum is omitted, the
        current line is assumed. If imbedded color commands are present in
        TextToCenter, they are processed.

           Variable InpStr,25,"PowerBatch"
           Variable MenuLine,19,"@004M@007enu Line 1"
           Center   "PowerBatch",2
           Center   InpStr,2
           Center   MenuLine,14

        Both of the first two examples will center the text "PowerBatch" on line
        2. The third example will center the text "Menu Line 1" on line 14.
        The value of the variable MenuLine contains imbedded colors commands.
        Note that the character,"@" is used to signify ASCII 001, a non-
        printable character. Refer to the notes on imbedded color commands.






























                                    Page 38





                                    CHDIR DirName

        DirName is made to be the current directory. If DirName contains a
        drive designation (i.e. C:\NEWDIR), a change will be made to the new
        drive prior to changing to the new directory.

           Variable Drive,3
           Variable Directory,79
           Write 'Enter new drive letter >'
           ReadKey  Drive
           Concat   Drive,':\'
           Write 'Enter new directory >'
           ReadStr  Directory
           Concat   Directory,Drive,Directory
           ChDir Directory

        The user is asked to enter a new drive and a new directory. These are
        then concatenated into the variable Directory. If the resulting value
        in Directory is "C:\NEWDIR", the ChDir command will change the logged
        (current default) drive to "C" and the logged directory to "\NEWDIR".



























                                    Page 39





                 CLEAR FGrndClr, [,BGrndClr] [,ClearChar] [BorderClr]

        The current defined screen will be cleared. This may have been altered
        with a Window command, if so, only the defined window will be cleared.
        The screen will be cleared to FGrndClr, BGrndClr. If ClearChar is
        specified, the screen will be cleared to this character, else it will
        be cleared to spaces. If the current defined screen is 1,1,80,25; the
        border will be set to BorderClr. The border may be "cleared" to normal
        with a clear command with BorderClr set to black.

           Variable ColorAttr,3,112 ;define wht on black
           Clear ColorAttr      ;clear to composite color 112
           Clear 7,0,'░'     ;clear to white on black using
           ; the char ░ to create a
                          ; pattern
           Clear 4,0,,4      ;clear to red on black with
                          ; red border, no pattern






























                                    Page 40





                  CLEARBOX UX,XY,LX,LY, FgClr, [BkgClr] [,ClearChar]


        Clear the interior of the box whose upper left coordinates (X,Y) are
        UX,UY and whose lower right coordinates (X,Y) are LX,LY. Clear the
        interior of the box to foreground color FgClr and background color
        BkgClr. This command clears the "inside" of the box, not the lines
        which describe the box. If ClearChar is specified, the interior of the
        box is propagated with the clear character.

           Variable ULX,2,5     ;upper left col value
           Variable ULY,2,3     ;upper left row value
           Variable LRX,2,75    ;lower right col value
           Variable LRY,2,20    ;lower right row value
           Variable BoxFore,2,4 ;foreground color red
           Variable BoxBack,2,0 ;background color black
           Box1     ULX, ULY, LRX, LRY, BoxFore, BoxBack
           ClearBox 5,3,75,20,112

        In this example we define the upper right and lower left coordinates
        of the box as well as the colors BoxFore and BoxBack. We draw the box
        with a red line on a black background. The ClearBox command clears the
        interior of the box to white on black.

           ClearBox ULX,ULY,LRX,LRY,BoxFore,BoxBack,'▓'

        This command clears the box to red on black and completely fills the
        box with the character "▓".



















                                    Page 41





                    CLEARLINE LineNum, ForeGrndClr [,BackGrndClr]

        Clear the line number specified by LineNum to a foreground color of
        ForeGrndClr and a background color of BackGrndClr. The line number is
        relative to the top of the current window. If you have defined a
        window with one of the PowerBatch window commands, the ClearLine command
        will be relative to the top left of this current window.

           Variable    Red,1,4
           Variable    Blue,1,1
           Variable    RedOnBlue,2,20
           Variable    CurrLine,2,12
           ClearLine      12,Red,Blue
           ClearLine      CurrLine,RedOnBlue

        Both examples of the ClearLine command clear line 12 on the screen to
        red foreground color and blue background color.

           Window1     20,5,60,10,32
           ClearLine      3,26

        This command will clear the third line of the defined window (the
        eighth absolute line on the physical screen), i.e. the third line down
        from the top of the window.























                                    Page 42





                         COLOR ForeGroundClr [,BackgroundClr]

        Set the default system color to a foreground color of ForeGroundClr
        and to a background color of BackgroundClr or optionally set the
        system color to the composite color attribute ForeGroundClr.

           Variable RedOnBlue,2,20
           Color 4,1
           Color MenuClr

        Both examples set the default color to red on blue for any text
        written to the screen without specific color instructions.



































                                    Page 43





                     COMPARE Value1, Value2, 1GR2,  1Less2, 1EQ2

        Compare the contents of Value1 to the contents of Value2. If Value1 is
        greater than Value2 jump to the Label 1GR2. If Value1 is less than
        Value2 jump to the label 1Less2. If Value1 is equal Value2 jump to the
        label 1EQ2. If the contents of the first two operands (Value1, Value2)
        are numeric then a numeric compare is performed otherwise an
        alphabetic compare is made. (If 19 is compared alphabetically to 2,
        then 2 is greater than 19; if it is compared numerically, 19 is
        greater than 2.)

           Variable InChar,1
           Variable Yes,1,"Y"
           Variable No,1,"N"
           GoToXY   4,23
           ReadYN   "Incorrect entry...Continue [Y/N] ",InChar
           Compare  InChar,"Y",NoIn,NoIn,YesIn
           Compare  InChar,Yes,,,YesIn   (Not Y falls through)
           Compare  InChar,"Y",NoIn,NoIn (Y falls through)

        In the first example, variable InChar is compared to literal "Y". If
        InChar is greater than "Y" then the program will jump to the label
        NoIn; if InChar is less than "Y", the program also jumps to the label
        NoIn; if InChar is equal to "Y", the program will continue processing
        at the label named YesIn. In the second compare, the variable InChar
        is compared to the variable Yes which has an assigned value of "Y". If
        InChar contains anything but "Y", the program continues with the next
        instruction after the compare command (it is said to fall through); if
        InChar contains "Y", the program will jump to the label YesIn. In the
        third compare command, variable InChar is compared to the literal "Y".
        If the variable InChar contains "N" (ReadYN prevents any entry but Y
        or N) the program jumps to the label NoIn otherwise it continues with
        the instruction after the compare command.














                                    Page 44





                          CONCAT Target, String1 [,String2]

        If String2 is omitted, String1 is appended to Target. If String2 is
        present, String2 is appended to String1 and the result replaces
        Target.

           Variable    OutMsg,78
           Variable    ErrMsg," is not a valid Drive letter."
           Variable    DriveLtr,1
           WriteAt     6,17,"Enter your source drive letter "
           ReadUpKey      DriveLtr
           ?DriveExist DriveLtr,DriveOK
           Concat      OutMsg, "[19] ", DriveLtr
           Concat      OutMsg, " is not a valid Drive letter."
           WriteAt     5,23,OutMsg

        In this example we ask the user to input a valid drive letter and
        verify this drive with the ?DriveExist command. If the drive is not
        valid we concatenate "[19]" (the error number) plus the drive letter
        entered by the user into the variable OutMsg. We then concatenate the
        error message (" is not a valid Drive letter.") onto the contents of
        OutMsg. The result would be something like "[19] L is not a valid
        Drive letter."
























                                    Page 45





                                  CURSOR CursorType

        CursorType may be 1,2, 3 or 4. 1 = normal cursor; 2 = cursor off; 3 =
        fat cursor; 4 = block cursor. A "fat" cursor is the cursor shape
        normally seen when text is to be inserted. The block cursor fills the
        entire screen position. Remember to set the cursor back to normal at
        the end of a program if you have set the cursor off during the
        processing of your program. This is not automatically set back to
        normal when the program terminates.

           Variable Normal,1,1
           Variable Off,1,2
           Variable Fat,1,3
           Variable Block,1,4

           Cursor   Off
           Cursor   2
           Cursor   Fat,1
           Cursor   3
           Cursor   Block
           Cursor   4
           Cursor   Normal
           Cursor   1

        Each preceding pair of commands will have the same results. Off has a
        value of 2, Fat has a value of 3, etc.





















                                    Page 46





                    DIVIDE Result, Divisor [,RtnCode] [,Decimals]

        If the divisor is less than 1 then Result is set to zero. Result is
        divided by Divisor and the result  of the division is placed in
        Result. If the division operation contained no errors, RtnCode will
        contain zero (0). The number of decimal places in the Result is
        specified in Decimals. If Decimals is not specified, zero decimal
        places will be assumed and integer arithmatic will be performed. Your
        result will be rounded to the number of specified decimal places.
        Accurate to 18 significant digits.

           Variable Result,18
           Variable RtnCode,1

           SetVar   Result,15
           Divide   Result,3    (Result now contains 5)

           SetVar   Result,'.000124'
           Divide   Result,'.00515',RtnCode,10
                    (Result contains 0.0240776699)



























                                    Page 47





                                 ENHANCLR Mode

        The enhanced color command assigns new background colors to the color
        values above 127 (the blinking colors). The new colors have a
        background color which is identical to the foreground colors. Run the
        new COLORS utility to view the new color values.  Mode is either 0
        (off); or 1 (on). Enhanced colors may be switched on or off at any
        time and the current screen will be changed.

           Variable    On,1,1
           Variable    Off,1,0


           EnhanClr    On

































                                    Page 48





                                       FLUSHKEY

        Removes all characters from the system keyboard buffer. After
        execution of this command, there will be no more characters waiting to
        be retrieved from the keyboard buffer. Use this command to eliminate
        the possibility of any "type ahead" characters being present in the
        buffer when you ask for input from the user.

           WriteLine   'CAUTION, You will now format your hard disk'
           FlushKey
           ReadYN   'Format hard Disk (Y/N)? ',InputChar



































                                    Page 49





                                     GOTO Label1

        Jump to the statement identified as command label Label1. Program
        processing will go directly from this GoTo command to Label1 and
        continue with the command immediately following the label (since the
        label command is simply a placemarker).

           GoTo     Error
           GoTo  EndOfPgm






































                                    Page 50





                               GOTOXY XCo-ord, YCo-ord

        Move the cursor to the column (X) specified in XCo-ord and row (Y)
        specified in YCo-ord.

           Variable CurrX,2
           Variable CurrY,2
           GoToXY   CurrX, CurrY
           GoToXY   12,6

        In the first example the cursor is moved to the location specified by
        the contents of variable CurrX and CurrY. In the second example, the
        cursor is moved to the location specified by two literals "12" and
        "6".

































                                    Page 51





                                  HALT [ErrorLevel]

        Halt your PowerBatch program and set DOS errorlevel to ErrorLevel.

           Variable Error14,2,14   ;define Error14 as "14"
           Halt     99
           Halt     Error14

        In the first usage of the Halt command, the PowerBatch program is halted
        and the DOS errorlevel is set to 99. In the second usage the program
        is halted and the DOS errorlevel is set to the contents of variable
        Error14 ("14").



































                                    Page 52





                                   LABEL LabelName

        Define a location in your source that will enable execution to begin
        immediately following the Label command without necessarily having
        executed the command immediately prior to the label. Jump immediately
        to this location in the command stream. See the discussion on labels
        at the beginning of this section.

           Label    MatchErr
           Label    EndOfPgm





































                                    Page 53





           LOCSTR  StrToLookFor, StrToLookIn, [Occur] ,Loc [,Replace]

        Examine the string StrToLookIn for the string StrToLookFor. If Occur
        does not exist set Occur to 1. Look for the Occur occurrance of the
        string. If StrToLookFor is found, place the location of the first
        position of the string in Loc; if StrToLookFor is not found, place
        zero (0) in Loc. If Replace is present, replace StrToLookFor with
        Replace.

           Variable    StrLoc,3
           Variable    InPutStr,255,'This is a test string'
           LocStr      'is',InPutStr,,StrLoc
        StrLoc will contain 3 ("This" contains 'is'),

           LocStr      'is',InPutStr,2,StrLoc
        StrLoc will contain 6.

           LocStr      'test',InPutStr,,StrLoc,'text'
        StrLoc will contain 11 and InPutStr will be changed to "This is a text
        string".

           LocStr      'test',InPutStr,2,StrLoc,'text'
        StrLoc will contain 0 and InPutStr will not be changed. There is no
        second occurrance of "test".























                                    Page 54





                             LENGTH StringLength, String

        Calculate the length of the string in variable String and place the
        result in StringLength.

           Variable InString
           Variable StrLen

           WriteAt  12,14,"Enter your current directory "
           ReadStr  InString

        User enters c:\util.

           Length   StrLen, InString

        StrLen will contain 7, the length of "c:\util".































                                    Page 55





                                     LOWER String

        Change the alphabetic characters in the variable String to lower case.

           Variable InString,25
           ReadStr  InString

        User enters C:\UTIL.

           Lower InString

        Now contains c:\util.



































                                    Page 56





                    MIDSTRING NewString, OldString, Offset, Length

        Create a NewString by extracting characters from OldString. Beginning
        with the Offset character of OldString, extract Length characters and
        create the new string.

           Variable Path,79
           WriteAt  1,2,"Enter Drive and Directory name "
           ReadStr  Path

        User enters C:\UTIL.

           MidString   Drive,Path,1,2

        Extract C: from C:\UTIL, making the newstring C:.
































                                    Page 57





                    MULTIPLY Result, Number [,RtnCode] [,Decimals]

        Result is multiplied by Number and the result of the multiplication is
        placed in Result. If the Multiply operation completed without error,
        RtnCode will contain zero (0). The number of decimal places in the
        result is specified in Decimals. If Decimals is not specified, zero
        decimal places will be assumed and integer arithmatic will be
        performed. Your Result will be rounded to the number of decimal places
        specified.

           Variable Total,14
           Variable TaxRate,6,'.06875'
           Variable Tax,8
           Variable Units,4
           Variable Quantity,3

           SetVar   Total,Units          (124)
           Multiply Total,Quantity          (372)
           Write 'Your total quantity is '
           WriteLine   Total
           Multiply Total,Cost,RtnCode,2    (948.6)
           SetVar   Tax,Total               (948.6)
           Multiply Tax,TaxRate,RtnCode,2      (65.22)
























                                    Page 58





                                        NORMAL

        Change the current color attribute(s) back to the definition prior to
        the execution of a BLINK or REVERSE command.

           Color 20    ;set default color to red on blue
           Blink       ;changes to blinking red on blue
           WriteAt  2,24,"Incorrect...re-enter!"
           Normal         ;resets color to 20
           Beep     800,8
           Wait     35    ;pause 3.5 seconds
           WriteAt  2,24,"                    "   ;clear msg

        This is an example of a typical error routine. The color attribute is
        changed to blinking with the Blink command. The error message is
        written and the color attribute is changed back to its original value
        with the Normal command. The speaker is "beeped" and after a wait of
        3.5 seconds, the error message is removed from the screen.





























                                    Page 59





                    PRINT PrinterNumber, StringToPrint [,RtnCode]


        PrinterNumber is 1,2, or 3; this corresponds to LPT1, LPT2, and LPT3.
        The Print command will send the StringToPrint to the printer and WILL
        NOT append a carriage return/line feed. This allows you to build your
        print line with a series of Print statements and complete the line
        with a PrintLine statement to force a CR/LF. While RtnCode is not
        required, it is highly recommended. If RtnCode contains zero (0), your
        print operation was successful. If it is not zero, your print
        operation was not successful. The error code returned varies with the
        make of printer, but the following seem to be somewhat universal.

        RtnCode = 8.   Printer not in ready state (printer off line).
        RtnCode = 40.  Printer out of paper.
        RtnCode = 48.  Printer not connected or power not on.

           Variable    PrtLine,80
           Variable    RtnCode,3
           Variable    PrtError,,'Printer Error!!Check your printer'

           SetVar      PrtLine,''
           Print    1,PrtLine,RtnCode
           Compare     RtnCode,0,,,PrtReady
           Write    PrtError
           ReadKey     InKey
           Label PrtReady
           SetVar      PrtLine,InData
           Print    1,PrtLine,RtnCode
           Compare     RtnCode,0,,,NextLine

















                                         Page 60





                  PRINTLINE PrinterNumber, StringToPrint [,RtnCode]

        PrinterNumber is 1,2, or 3; this corresponds to LPT1, LPT2, and LPT3.
        The PrintLine command will send the StringToPrint to the printer and
        WILL append a carriage return/line feed. While RtnCode is not
        required, it is highly recommended. If RtnCode contains zero (0), your
        print operation was successful. If it is not zero, your print
        operation was not successful. The error code returned varies with the
        make of printer, but the following seem to be somewhat universal.

        RtnCode = 8.   Printer not in ready state (printer off line).
        RtnCode = 40.  Printer out of paper.
        RtnCode = 48.  Printer not connected or power not on.

           Variable    PrtLine,80
           Variable    RtnCode,3
           Variable    PrtError,,'Printer Error!!Check your printer'

           SetVar      PrtLine,''
           Print    1,PrtLine,RtnCode    ;is the printer rdy?
           Compare     RtnCode,0,,,PrtReady
           Write    PrtError
           ReadKey     InKey
           Label PrtReady
           SetVar      PrtLine,InData
           PrintLine      1,PrtLine,RtnCode
           Compare     RtnCode,0,,,NextLine




















                                    Page 61





                                       PRINTSCR

        The entire contents of the current screen is sent to the system
        printer. A page eject is automatically appended to the last character
        to cause the printer to eject the printed page.










































                                    Page 62





                                 PROMPT NewPromptVal

        Change the current value of the prompt to the value specified in
        NewPromptVal.

           Prompt   "$P$G"









































                                    Page 63





                              RANDOM UpperLimit, Result

        A random number is generated from (and including) zero through the
        UpperLimit. The random number is placed in Result.

           Variable RandNum,3

           Random   200,RandNum

        A random number between 0 and 200 inclusive will be generated.

           Label NewNumb
           Random   200,RandNum
           Compare  RandNum,100,,NewNumb

        This will generate a random number between 100 and 200.































                                    Page 64





               READKEY Target [,SpecInd] [,Tmeout] [,NoPrt] [,CtlChar]

        Read a single key from the keyboard and place the result in Target. If
        SpecInd contains a "1" after reading the key from the keyboard, then a
        "special key" has been returned in Target. Special keys are function
        keys, Page Up/Down, cursor movement keys, etc. If you are in doubt
        about a particular key, run the program "KEYID" (furnished on the
        install disk). Each key you press will be identified as either a
        regular key or a special key and the value that will be returned in
        Target when this key is pressed (remember that SpecInd will contain a
        "1" for special keys).

         The TmeOut parameter is used when you want to wait for a key from the
        keyboard, but continue processing without receiving the key after a
        specified number of seconds. Placing the number of seconds to wait in
        TmeOut will allow your program to "fall through" the ReadKey
        instruction if the timeout value is exceeded. If no input is received
        within TmeOut seconds, the null character (ASCII 0) is placed in
        Target and zero is placed in SpecInd.

        The NoPrt parameter gives you the option to have the entered character
        printed or not. The default is to print the character. If you wish to
        have the character not printed to the screen, place a one (1) in the
        NoPrt parameter.

        ReadKey gives you the capability to check for Non-ASCII keys (i.e.
        NumLock, Scroll Lock, etc.). Place one of the characters from the
        following table in the CtlChar parameter. If the requested key is
        pressed on the keyboard (or toggled on in the case of NumLock, Scroll
        Lock, and Caps Lock), ReadKey will return with SpecInd set to 2. No
        key will be returned in Target. Select one of these values to be
        placed in CtlChar:
           Right Shift #1    Left Shift     #2
           Ctrl        #4    Alt         #8
           Scroll Lock #16      Num Lock #32
           Caps Lock   #64      Insert      #128











                                    Page 65





                           Variable InKey,1
           Variable Spec,1
           Variable F10,1,#68
           Variable Caps,1,#64

           ReadKey  InKey          ;read a single key

           ReadKey  InKey,Spec
           Compare  Spec,1,Reg,Reg       ;fall thru if Spec=1
           Compare  InKey,F10,NotF10,NotF10 ;fall thru if F10

           ReadKey  InKey,Spec,10        ;wait 10 secs
           Compare  InKey,'',,,NoKey     ;InKey=null, timedout

           ReadKey  InKey,,,1            ;dont print the input

           ReadKey  InKey,Spec,,,Caps
           Compare  Spec,2,,,CapsOn      ;Spec=2, caps lock on
           Write 'Caps Lock is off'




























                                    Page 66





                              READSTR Target [,TimeOut]

        Read a string of characters from the keyboard until the user presses
        the enter key. Any number of characters may be read up to the maximum
        length specified for Target in the Variable statement. If the TimeOut
        parameter is specified, wait the specified number of seconds before
        continuing without having received a key.

           Variable InString,12
           ReadStr  InString    ;12 chars max will be read

           Label ReadPass
           ReadStr  InString,10 ;Only wait 10 secs for input
           Compare  InString,'',InputOK
           WriteAt  12,24,'Please enter your password'
           GoTo     ReadPass

           Label InputOK





























                                    Page 67





                             READUPKEY Target [,TimeOut]

        Read a single character from the keyboard, changing the case of any
        alphabetic character to upper case and place this upper case character
        in Target. If the TimeOut parameter is present, continue with the
        execution of the program after TimeOut seconds even if no character is
        entered.

           ReadUpKey   CharIn   ;read a single char in upper case

           WriteAt  16,24,'Enter your drive letter'
           ReadUpKey   CharIn,10      ;wait 10 seconds for a key
           Compare  CharIn,'',GotDrive,GotDrive
           SetVar   CharIn,'C'  ;supply default drive letter

           Label GotDrive































                                    Page 68





                     READYN Message, Target [,TimeOut][,NoPrint]

        Write the message found in Message at the current cursor location and
        wait for a single key to be entered from the keyboard. Force the user
        to enter either a "Y" or "N" and place the upper case "Y" or "N" in
        Target. If TimeOut is specified, wait only the specified number of
        seconds before continuing with the program without input. If the
        character entered is not to be printed, place a one (1) in NoPrint.

           Variable Msg4,35,"Invalid name...Continue [Y/N] "
           ReadYN   "Invalid name...Continue [Y/N] ",CharIn

           ReadYN   Msg4,CharIn

        In both usages of the ReadYN command, the message "Invalid
        filename...Continue [Y/N] " will be displayed and the program will
        wait for a response from the user. If the user enters any characters
        other than "Y", "y", "N", or "n" the system speaker will sound and the
        user is prompted again for input. At the completion of this command,
        the variable CharIn will contain either "Y" or "N" (always upper
        case).

           Label ErrMsg
           ReadYN   Msg4,CharIn,8
           Compare  CharIn,'',GotChar
           Beep     800,8
           GoTo     ErrMsg

        If the user does not enter a character within 8 seconds, the system
        speaker will be sounded and the user asked again for input.

















                                    Page 69





                                       REVERSE

        Change the text attributes to "reverse video". This is accomplished by
        swapping the foreground and background attributes. This command is
        "undone" by using NORMAL.

           Color 20    ;red on black
           Reverse        ;color is changed to black on red
           WriteAt  1,15,"Press Escape To Continue"
           Normal         ;color is now red on black





































                                    Page 70





                                     SCRMODE Mode

        Used for changing the screen mode to 43/50 lines per screen on
        monitors that have the capability to display in these modes. The mode
        shift will automatically detect either 43 or 50 lines and change to
        the proper mode. Mode 0 will switch from 43/50 to 25 lines per screen.
        Mode 1 will switch from 25 lines to 43/50 lines per screen.

           Variable 25Lines,1,0 ;define a var with value 0
           Variable 43Lines,1,1 ;define a var with value 1

           ScrMode     43Lines
           Perform     DisplayParms   ;display a file
           ScrMode     25Lines        ;return to normal screen display

































                                    Page 71





                           SETENV EnvironName EnvironValue

        The environment variable named EnvironName will have its value changed
        to EnvironValue. Error messages will occur if the size of the new
        value minus the size of the old value is greater than the number of
        free bytes of environment space available.

           Variable    VarName,7,"MONITOR"
           Variable VarValue,5,"color"

           SetEnv   VarName, VarValue
           SetEnv   "Monitor","color"

        Both examples will change the environment variable "Monitor" to have a
        value of "color".
































                                    Page 72





                                   SETPATH NewPath

        The current PATH environment variable will have its value changed to
        NewPath. Error messages will occur if the size of the new path value
        minus the size of the old value is greater than the number of free
        bytes of environment space available.

           Variable NewPath,40,"d:\;c:\util\exec;c:\wp\letters"

           SetPath  NewPath
           SetPath  "d:\;c:\;"




































                                    Page 73





                              SETVAR VariableName, Value

        Set the value of VariableName to the contents of Value. A variable
        cannot be set to a value greater in length than the  maximum length
        parameter in the Variable definition.

           Variable ErrCode,3
           Variable FileName,79

           SetVar   ErrCode,99
           SetVar   FileName,"C:\CONFIG.SYS"

        In the first usage of the SetVar command, the variable ErrCode is set
        to "99" and the second usage sets the variable FileName to
        "C:\CONFIG.SYS".
































                                    Page 74





                    SUBTRACT Total, Number [,RtnCode] [,Decimals]

        Subtract the contents of Number from the contents of Total and place
        the result in Total. If the subtract operation completed without
        error, RtnCode will contain zero (0). The number of decimals in Total
        is specified in Decimals. If Decimals is not specified, zero decimal
        places will be assumed and integer arithmatic will be performed. The
        Total is rounded to the specified number of decimal places.

           Variable TotalLines,2,25
           Variable RtnCode,1

           Subtract TotalLines,1
           Compare  RtnCode,0,ErrRoutine

        Subtract the constant "1" from the variable "TotalLines" and place the
        result in TotalLines.

        Using decimal arithmatic in PowerBatch...

           Variable TotAmt,12
           Variable TaxAmt,10

           SetVar   TaxAmt,TotAmt
           Multiply TaxAmt,'.025',RtnCode,3
           Subtract TotAmt,TaxAmt,RtnCode,2





















                                    Page 75





                      TRIM  StrToChg [,Indicator] [,CharToTrim]

        StrToChg is the string to be "trimmed". Indicator is (L)eft, (R)ight,
        or (B)oth indicating which end of the string is to be trimmed. If
        Indicator is not specified, (R)ight will be assumed. CharToTrim is the
        character which will be trimmed from the string. If no CharToTrim is
        specified, blanks will be trimmed from the string.

           Variable    InString,80

           ReadFile    'INPUT',InString
           Trim        InString

        If there are any trailing blanks read from the file, the Trim command
        will eliminate these trailing blanks. (No character was specified and
        blank was assumed; no indicator was specified and Right was assumed.

           Variable    Total,11
           Variable    Left,1,'L'
           Variable    Zero,1,'0'

           Trim        Total,Left,Zero

        Here the Trim command is used to remove leading (left end) zeros from
        a numeric field.






















                                    Page 76





                                  UPPER VariableName

        Change all the alphabetic characters in VariableName to upper case.

           Variable InString,25
           WriteAt  14,25,"Enter your directory name "
           ReadStr  InString       (user enters c:\util)
           Upper    InString    (changed to C:\UTIL)
           ?InPath  InString,GoodDir  (path is always upper case)

        In this example, the user is prompted for a path name to be entered.
        The path name is to be compared to the system path for validity. Since
        the contents of the system path are always in upper case, we change
        the InString variable to upper case prior to comparison.

































                                    Page 77





                   VARIABLE VariableName, MaxLength [,InitialValue]

        Define a variable to be used in a PowerBatch program. The variable will
        have a maximum length of MaxLength and an initial value of
        InitialValue. The initial value may be either an alphabetic value, a
        numeric value, or an ASCII value. An initial value which is alphabetic
        must be enclosed in either single or double quotes. A numeric initial
        value may be defined with or without quote delimiters but a convention
        of no quotes is a recommended technique. An  ASCII value is expressed
        as #nnn where nnn is the decimal value of the ASCII character. A
        variable may be of any length from 1 through 255. The initial value
        may be of any length from 1 through the MaxLength. VariableName is the
        name which you give to this variable and the means by which you refer
        to the variable in other PowerBatch commands.  See the discussion on
        variables at the beginning of this section.

        The special variables CLP%1 - CLP%16 are used to receive Command line
        parameters passed to a compiled PowerBatch program. Any command line
        parameters will be found in these  special parameters only.  Any
        number of parameters up to the max of 16 may be passed.

        Define a variable with no initial value.
           Variable DayOfWeek,9

        Define an alpha variable with an initial value.
           Variable ErrMsg1,25,"Invalid directory name."

        Define a variable with an initial numeric value of 50.
           Variable PauseTime,2,50

        Define a variable as a single ASCII value.
           Variable RightArrow,1,#26

        Define a variable as a string of ASCII values.
           Variable DblLine,5,#205#205#205#205#205

        Define a variable to receive a command line parameter.
           Variable CLP%1,12









                                    Page 78





                                WAIT TimeToWait

        Cause the execution of a PowerBatch program to pause for a specified
        amount of time. TimeToWait is expressed in tenths of a second.

           Variable PauseTime,2,50
           Wait     5     (pause half a second)
           Wait     PauseTime   (pause 5 seconds)
           Wait     35    (pause 3.5 seconds)






































                                    Page 79





                  WINDOW0-3 UpX,UpY,LoX,LoY,FGClr [,BKClr]
                  WINDOW4 UpX,UpY,LoX,LoY,FGClr [,BKClr] [,ShadClr]

        A virtual screen is defined with the boundaries UpX, UpY, LoX, LoY.
        The color attributes for this new screen are set to FGClr, BKClr. The
        area enclosed within this new screen is not cleared. Each window type
        has a different frame drawn around the window.

           Window0     No frame
           Window1     Single line
           Window2     Double line
           Window3     Heavy line
           Window4     Single line with shadow

        The cursor is positioned in the upper left corner of the window
        (location 1,1 for the new screen). This virtual screen will wrap at
        the new column boundaries and scroll at the new row boundaries. This
        screen appears in every way to DOS as the full size of the screen.





























                                    Page 80





                      WRITE StringToWrite [,ForeClr] [,BackClr]

        Write the string contained in StringToWrite at the current cursor
        location using foreground color attribute ForeClr and background color
        attribute BackClr. In the absence of ForeClr and BackClr use the
        current color attributes. If the string contains imbedded color
        attributes, change the colors in the string according to these values.
        (See Imbedded Color Commands). The string is not followed by a
        carriage return, line feed pair (i.e. the cursor is not moved to the
        first position of the next line).

        Write the string "Enter your password" in black on white.
           Write "Enter your password ",0,7

        Write "Invalid directory name" contained in a variable using the
        composite color 112, also contained in a variable.
           Variable ErrMsg1,25,"Invalid directory name."
           Variable ErrClr,3,112
           Write ErrMsg1,ErrClr

        Write the string "Menu of choices" with the "M" in Menu written in
        color 112 and the remainder of the string written in  color 31.
           Variable MenuTitle,23,'@112M@031enu of choices'
           Write MenuTitle























                                    Page 81





                 WRITEAT XLoc, YLoc, StringVal [,ForeClr] [,BackClr]

        Write the value contained in StringVal at column location contained in
        XLoc and at row location contained in YLoc using the foreground color
        attribute contained in ForeClr and the background color attribute
        contained in BackClr. In the absence of ForeClr and BackClr, use the
        current color attributes. The string is not followed by a carriage
        return, line feed pair (i.e. the cursor is not moved to the first
        position of the next line).

           Variable TitleClr,3,112
           Variable CurrX,2
           Variable CurrY,2
           Variable CompName,25,"The ABC Company"
           WriteAt  15,3,"The ABC Company",TitleClr
           WriteAt  CurrX,CurrY,CompName

        In the first usage of the WriteAt command, the literal "The ABC
        Company" is written at column 15, row 3. In the second usage, the
        contents of the variable CompName ("The ABC Company") is written at
        the column location specified by the contents of variable CurrX and at
        the row location specified by the contents of variable CurrY.

























                                    Page 82





                        WRITELINE StringToWrite [,LineNumber]

        Write the string contained in StringToWrite beginning at position 1 of
        the line number specified in LineNumber. Follow the string with a
        carriage return line feed pair (i.e. move the cursor to the first
        position of the next line). In the absence of LineNumber write the
        string at the current cursor location. Expand any imbedded color
        commands in the string. (See note below on imbedded color commands).

           WriteLine "Please read these instructions ",7

        The message "Please read these instructions " is written beginning in
        column 1 of row 7. Follow the string with a CR/LF.

           WriteLine Msg5

        Write the contents of the variable Msg5 beginning at the current
        cursor location. Follow the string with a CR/LF.

           Write "Enter the letter of the selected drive > "
           ReadKey  InKey
           WriteLine   ""

        Write the string "Enter the letter of the selected drive > ", leaving
        the cursor positioned at the end of this message (the Write command
        does not supply a CR/LF. After receiving the entry from the user,
        position the cursor at the beginning of the next line by "writing" to
        the screen a null string (two quote marks without any character
        between) using the WriteLine command. This will write to the screen
        only a CR/LF.

















                                    Page 83





                                  STANDARD VARIABLES

        There are several variables which are in every PowerBatch program. These
        Standard Variables may be referenced without having to define them
        with a Variable command.

                DispAdapter - This 4 character variable will contain a code describing
           the type of display controller card located in your system. If the
           first character contains "M", the adapter is a monochrome adapter.
           If the first character contains "C", the adapter is a color
           adapter. The remaining 3 characters may contain:
                 MDA-Monochrome Display Adapter
                 CGA-Color Graphics Adapter
                 EGA-Extended Graphics Adapter
                 VGA-Video Graphics Array
                 MGA-Multi-color Graphics Array
              If no video adapter is found the field will contain "NONE".

                DOSError - If the external program which you execute sets a DOS error
           code, the error code will be placed in this variable.

                DOSVer - This field will contain a 4 character code for the version of
           DOS installed. The first two characters are the major version and
           the last two the minor version. DOS 6.0 will be reported as 0600.

                ErrorLevel - If the external program which you execute sets an
           ErrorLevel and that ErrorLevel is returned to PowerBatch by DOS, it
           will be placed in this variable.

                ParallelPorts - This variable will contain the number of parallel ports
           supported by your hardware.

                SerialPorts - This variable will contain the number of serial ports
           supported by your hardware.













                                    Page 84





                                Command Summary

        ?Color      Foreground Background Composite
        ?CurrDir    CurrDrive CurrDirectory
        ?Date       DayOfWeek Month Day Year
        ?DirExist   DirName FoundLbl [NotFoundLbl]
        ?DiskInfo   DriveLetter VolID DriveType
        ?DiskSpace  DriveLetter TotalSpace FreeSpace
        ?DriveExist DriveLetter ValidLabel [InvalidLabel]
        ?EnvStr     EnvironName EnvironNameContents
        ?FileExist  FileName FoundLabel [NotFoundLabel]
        ?FileExpan  FileName FoundLabel [NotFoundLabel]
        ?FileSize   FileSize FileName
        ?Inpath     DirName FoundLabel [NotFoundLabel]
        ?Time       CurrentTime
        Add         Sum Number [RtnCode] [Decimals]
        Beep        Frequency Duration [Repeat]
        Blink
        Boot
        Box0-3      Ux Uy Lx Ly ForeClr [BackClr]
        Box4        Ux Uy Lx Ly ForeClr [BackClr] [ShadowClr]
        BreakOn
        BreakOff
        Center      TextToCenter LineNum
        ChDir       DirName
        Clear       FgrndClr [BgrndClr] [ClearChar] [BorderClr]
        ClearBox    Ux Uy Lx Ly FgClr [BkgClr] [ClearChar]
        ClearLine   LineNum ForeGrndClr [BackgrndClr]
        Color       ForeGroundClr [BackGroundClr]
        Compare     Value1 Value2 1GR2 [1Less2] [1Eq2]
        Concat      Target String1 [String2]
        Cursor      CursorType (1=Normal,2=Off,3=Fat,4=Block)
        Divide      Result Divisor [RetCode] [Decimals]
        EnhanClr    Mode
        GoTo        Label
        GoToXY      XCo-ord YCo-ord
        Halt        [ErrorLevel]
        Label       LabelName
        Length      StringLength String
        LocStr      LookFor LookIn [Occur] Loc [Replace]
        Lower       String
        MidString   NewString OldString Offset Length
        Multiply    Result Number [RtnCode] [Decimals]
        Normal
        Print       PrinterNum StrToPrint [RtnCode]


                                    Page 85





        PrintLine   PrinterNum StrToPrint [RtnCode]
        PrintScr
        Prompt      NewPromptVal
        Random      UpperLimit Result
        ReadKey     Target [SpecInd] [Timeout] [NoPrt] [CtlChar]
        ReadStr     Target [Timeout]
        ReadUpKey   Target [Timeout]
        ReadYN      Message Target [Timeout] [NoPrt]
        Reverse
        ScrMode     Mode
        SetEnv      EnvironName EnvironValue
        SetPath     NewPath
        SetVar      VariableName Value
        Subtract    Total Number [RtnCode] [Decimals]
        Trim        StrToTrim [Indicator] [CharToTrim]
        Upper       VariableName
        Variable    VariableName MaxLength [InitialValue]
        Wait        TimeToWait (in tenths of a second)
        Window0-3   UpX UpY LoX LoY FgClr [BkClr]
        Window4     UpX UpY LoX LoY FgClr [BkClr] [ShadClr]
        Write       StringToWrite [ForeClr] [BackClr]
        WriteAt     XLoc YLoc StringVal [ForeClr] [BackClr]
        WriteLine   StringToWrite [LineNumber]

        Standard Variables

        DispAdapter Current display adapter
        DOSError Last DOS error code
        DOSVer      Running DOS version
        ErrorLevel  Last DOS errorlevel
        ParallelPorts  Num of parallel ports in running machine
        SerialPorts Num of serial ports in running machine















                                    Page 86





                               Compilation Errors

        Compilation errors are printed on the screen and also written in a
        file named ProgName.MAP where ProgName is the name of the program you
        have just compiled (If you have a split screen editor, view the source
        in one screen part and the errors in the other part). If the source
        line is available, the source line is printed above the error preceded
        by the line number count. Source lines are not available during the
        second pass of the compiler which may generate "Label not defined" and
        "Variable not defined" errors.

              "Not a valid command" - This error is generated when the first
              word on the command line is not a PowerBatch command and contains
              more than 8 characters.

              Example:
              13 Directory name checked here.
              [DIRECTORY] Not a valid command

                               Probably should be
              ;Directory name checked here

              "Missing variable" - A command contains less than the required
              number of operands.

              Example:
              21 ?Color   ForeColor,BackColor
              [] Missing variable

              Variable for the composite color byte is missing.

              "Expected a variable Name" - A string was found in an operand that
              may contain only a variable name.

              Example:
              10 ?Time "Current Time"
              [Current Time] Expected a variable name

              The current time may only be placed in a variable.

             "Quoted literal not terminated" - A single quote was encountered
              within a source line.

              Example:
              9 Center "Move Command,5


                                    Page 87





                 [] Quoted literal not terminated

              Closing quote should precede comma.

              "Invalid max length specified" - The second operand of a variable
              definition should specify the maximum length of the variable.
              The value found was not numeric.

              Example:
              3 Variable  CompName,"The ABC Company"
                [The ABC Company] Invalid max length specified

             "Variable not defined" - A reference to a variable was made in the
              source file but the variable was not defined with the Variable
              command.

              Example:
              [CURRDATE] Variable not defined

              "Duplicate variable" - The same variable name has appeared 2 or
              more times in a Variable definition statement.

              Example:
              7 Variable  CompName,25
              [COMPNAME] Duplicate variable

              "Duplicate label" - The same label name has appeared 2 or more
              times in a Label definition statement.

              Example:
              16 Label    Step2
              [STEP2] Duplicate label

              "Invalid hex definition in variable" - A variable definition
              contained a # not enclosed in quotes signifying a value
              definition by ASCII value. The characters following this # were
              not numeric or did not equate to an ASCII character.

              Example:
              Variable Return,2,#J#219

                 #J is not valid

              "External command >" - This is not an error message, but is a
              check to alert you to each command found in a PowerBatch source


                                    Page 88





              file that will be treated as an external command. External
              commands are DOS intrinsic commands, .COM, and .EXE commands or
              programs (even PowerBatch compiled programs) and .BAT (standard
              DOS batch files) that are to be executed by PowerBatch.

              Example:
              External command > 12 DIR  (DOS directory command)
              External command > 29 MYPROG (Exe module MYPROG)







































                                    Page 89





                                    Examples

        The source for several examples is contained on your installation
        disk. You may print these examples by entering:

           COPY INQUIRE.PWR LPT1

        These examples may be compiled using the PBPLUS command by entering a
        command similar to:

           PBPLUS INQUIRE <enter>

        This compiles the source for INQUIRE.


































                                         Page 90





                               IMBEDDED COLOR COMMANDS

        A literal or a variable may be defined which has color commands
        imbedded in the text of the literal allowing you to change the color
        in the middle of the string to be printed. If you were creating a
        tutorial and wanted a menu at the bottom of the screen that gave the
        user several command choices and you wanted this menu to have the
        first character of each command in reverse video, PowerBatch provides a
        means to accomplish this easily. Suppose the command line is:

           Next Prev Load ........

        and the N, P, and L were to be in reverse video you would define the
        variable (or literal) as:

           Variable Cmd,75,"@112N@007ext @112P@007rev @112L@007oad"

        IN THIS EXAMPLE THE @ REPRESENTS CTRL-A BECAUSE OUR PRINTER WILL NOT
        PRINT A CTRL-A!

        The syntax for imbedded color commands is Ctrl-A followed by the THREE
        digit color attribute. Thus @112 means change the color to 112 and
        continue printing in this color until another change is made. Further
        examining the line...@112N@007ext means change to color 112, print N,
        change to color 007, print ext (Next).

        The ASCII value of Ctrl-A is 001. Most text editors will allow you to
        enter an ASCII character by entering the actual ASCII value by
        pressing the Alt key and entering the ASCII value on the numeric
        keypad (not the numbers above the character keyboard). Thus entering
        Ctrl-A becomes as simple as pressing Alt-1.
















                                         Page 91





                             Composite Color Values

                             Color Names And Their Values

        Black (Blk)    0     Dk. Gray (DGy)    8
        Blue (Blu)     1     Lt. Blue (LBl)    9
        Green (Grn)    2     Lt. Green(LGr)    10
        Cyan (Cyn)     3     Lt. Cyan (LCy)    11
        Red (Red)      4     Lt. Red (Lrd)     12
        Magenta (Mag)  5     Lt. Magenta (LMg) 13
        Brown (Brn)    6     Yellow (Yel)      14
        Lt. Gray (LGy) 7     White (Wht)       15

        On the following page is two tables which give the ASCII value for the
        composite color byte (the single byte DOS uses to identify the current
        color). This single value is a composite of the two values for the
        background and foreground color values.  To arrive at the composite
        value multiply the background color value by 16 and add the foreground
        color value. Some examples will help explain:
           Red on Blue
           (Blue * 16) + Red = 20        (001 * 16) + 4 = 20

           White on Red
           (Red * 16) + White = 79       (004 * 16) + 15 = 79

        Verify these composite calculations by finding the corresponding
        values in the tables on the next page. To find Red on Blue, find the
        background color down the left side of the table and the foreground
        color across the top. Blue is the second color down and Red the fifth
        color across; at this intersection you will find the value 020.
        (Remember the color values begin with zero). Red is the fifth color
        down and White is the 16 color across; at this intersection is value
        079.














                                         Page 92





                          Normal (non-blinking) Colors


            Blk Blu Grn Cyn Red Mag Brn LGy DGy LBl LGr LCy LRd LMg Yel Wht
        Blk 000 001 002 003 004 005 006 007 008 009 010 011 012 013 014 015
        Blu 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031
        Grn 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047
        Cyn 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063
        Red 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079
        Mag 080 081 082 083 084 085 986 087 088 089 090 091 092 093 094 095
        Brn 096 097 098 099 100 101 102 103 104 105 106 107 108 109 110 111
        Gry 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127

        Colors Which Blink


            Blk Blu Grn Cyn Red Mag Brn LGy DGy LBl LGr LCy LRd LMg Yel Wht
        Blk 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
        Blu 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
        Grn 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
        Cyn 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
        Red 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
        Mag 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
        Brn 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
        Gry 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255






















                                         Page 93





        Border Color 40                      SetEnv 72
        Box 34, 35                         SetVar 74
        Box With Shadow 35                 ERRORLEVEL 13, 52, 84
        Case                               External Commands 12, 89
          Lower 56                         Field length
          Upper 68, 77                       maximum 67
        CD, ChDir 39                       File exists 25, 26
        Center A Line Of Text 38           File Size 27
        Color attribute 16, 17, 59         FileName
        Command Line Parameters 14, 78       Does It Exist 25
        Command Notation 15                  Full Path Name 26
        Command Summary 85                 Flush Keyboard 49
        Command Syntax 16                  Frame 34, 35
        Comments 9                         Imbedded Colors 91
        Compare                            Installation 6
          alphabetic 44                    Interior of a box 41
          numeric 44                       Introduction 1
        Compilation Errors 87              Keyboard Input
        Composite Color Values 92            ReadKey 65
        Concatenate Strings 45               ReadStr 67
        Concept Of Operation 4               ReadUpKey 68
        Ctrl - Break 36                      ReadYN 69
        Current Date 19                    Labels 11
        Current Directory 18               License Agreement 1
        Current Drive 18                   Literals 9, 10
        Current Time 29                    Monitor Type 84
        Cursor Postion 51                  ParallelPorts 84
        Directory 20                       Passing Parameters
        Directory Exists 20                  14
        Directory, Change to new 39        PATH 15
        Disk capacity 22                     Is Dir In 28
        Disk Drive                           SetPath 73
          Valid Letter 23                  Pause 79
        Disk Space                         Pause A Program 79
          Free 22                          PBPlus Commands
          Total 22                           ?Color 17
        DOS errorlevel 52                    ?CurrDir 18
        DOS search path 28                   ?Date 19
        DOS Version 84                       ?DirExist 20
        DOSERROR 13, 84                      ?DiskInfo 21
        Drive Type 21                        ?DiskSpace 22
        Drive, Change to new 39              ?DriveExist 23
        Environment Variables 14             ?EnvStr 24
          Contents 24                        ?FileExist 25



                                         Page 94





                                             ?FileExpand 26                                                                        Upper 77
          ?FileSize 27                       Variable 78
          ?InPath 28                         Wait 79
          ?Time 29                           Window 80
          Add 30                             Write 81
          Beep 31                            WriteAt 82
          Blink 32                           WriteLine 83
          Boot 33                          PROMPT 15
          Box 34, 35                       Random Numbers 64
          BreakOff 37                      Screen
          BreakOn 36                         Clear 40
          Center 38                          Color 43
          ChDir 39                         Screen Window 80
          Clear 40                         SerialPorts 84
          ClearBox 41                      SETENV 15
          ClearLine 42                     SETPATH 15
          Color 43                         Software Support 3
          Compare 44                       Standard Variables
          Concat 45                          DispAdapter 84
          Cursor 46                          DOSError 84
          Divide 47                          DOSVer 84
          FlushKey 49                        ErrorLevel 84
          GoTo 50                            ParallelPorts 84
          GoToXY 51                          SerialPorts 84
          Halt 52                          String length 55
          Label 53                         Syntax
          Length 55                          Compilation 7
          Lower 56                         System speaker 31
          MidString 57                     Time, Current 29
          Multiply 58                      Trademarks 1
          Normal 59                        Variable map 7
          PrintScr 62                      Variables 9
          Prompt 63                          Value Of 74
          Random 64                        Virtual Window 80
          ReadKey 65                       Volume ID 21
          ReadStr 67                       Window 80
          ReadUpKey 68                     ReadYN 69
          Reverse 70
          ScrMode 71
          SetEnv 72
          SetPath 73
          SetVar 74
          Subtract 75



                                         Page 95





        This page intentionally left blank for your notes...














































                                         Page 96